NumberFormat

class U_I18N_API NumberFormat : public Format

Abstract base class for all number formats

Inheritance:

Public Classes

enum EAlignmentFields

Alignment Field constants used to construct a FieldPosition object

INTEGER_FIELD: These constants are provided for backwards compatibility only, and are deprecated

Public Methods
virtual bool_t operator==(const Format& other) const: Return true if the given Format objects are semantically equal
virtual UnicodeString& format(const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const: Format an object to produce a string
virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const: Parse a string to produce an object
UnicodeString& format( double number, UnicodeString& output) const: Format a double or long number
virtual UnicodeString& format(double number, UnicodeString& toAppendTo, FieldPosition& pos) const: Format a double or long number
UnicodeString& format(const Formattable& obj, UnicodeString& result, UErrorCode& status) const: Redeclared Format method
virtual void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const: Return a long if possible (e
virtual void parse( const UnicodeString& text, Formattable& result, UErrorCode& status) const: Parse a string as a numeric value, and return a Formattable numeric object
bool_t isParseIntegerOnly(void) const: Return true if this format will parse numbers as integers only
virtual void setParseIntegerOnly(bool_t value): Sets whether or not numbers should be parsed as integers only
static NumberFormat* createInstance(UErrorCode&): Returns the default number format for the current default locale
static NumberFormat* createInstance(const Locale& inLocale, UErrorCode&): Returns the default number format for the specified locale
static NumberFormat* createCurrencyInstance(UErrorCode&): Returns a currency format for the current default locale
static NumberFormat* createCurrencyInstance(const Locale& inLocale, UErrorCode&): Returns a currency format for the specified locale
static NumberFormat* createPercentInstance(UErrorCode&): Returns a percentage format for the current default locale
static NumberFormat* createPercentInstance(const Locale& inLocale, UErrorCode&): Returns a percentage format for the specified locale
static NumberFormat* createScientificInstance(UErrorCode&): Returns a scientific format for the current default locale
static NumberFormat* createScientificInstance(const Locale& inLocale, UErrorCode&): Returns a scientific format for the specified locale
static const Locale* getAvailableLocales(int32_t& count): Get the set of Locales for which NumberFormats are installed
bool_t isGroupingUsed(void) const: Returns true if grouping is used in this format
virtual void setGroupingUsed(bool_t newValue): Set whether or not grouping will be used in this format
int32_t getMaximumIntegerDigits(void) const: Returns the maximum number of digits allowed in the integer portion of a number
virtual void setMaximumIntegerDigits(int32_t newValue): Sets the maximum number of digits allowed in the integer portion of a number
int32_t getMinimumIntegerDigits(void) const: Returns the minimum number of digits allowed in the integer portion of a number
virtual void setMinimumIntegerDigits(int32_t newValue): Sets the minimum number of digits allowed in the integer portion of a number
int32_t getMaximumFractionDigits(void) const: Returns the maximum number of digits allowed in the fraction portion of a number
virtual void setMaximumFractionDigits(int32_t newValue): Sets the maximum number of digits allowed in the fraction portion of a number
int32_t getMinimumFractionDigits(void) const: Returns the minimum number of digits allowed in the fraction portion of a number
virtual void setMinimumFractionDigits(int32_t newValue): Sets the minimum number of digits allowed in the fraction portion of a number
static UClassID getStaticClassID(void): Return the class ID for this class
virtual UClassID getDynamicClassID(void) const: Override Calendar Returns a unique class ID POLYMORPHICALLY

Protected Methods
NumberFormat(): Default constructor for subclass use only
NumberFormat(const NumberFormat&): Copy constructor
NumberFormat& operator=(const NumberFormat&): Assignment operator

Inherited from Format:

Public Methods
bool_t operator!=(const Format& other) const
virtual Format* clone() const

Documentation

Abstract base class for all number formats. Provides interface for formatting and parsing a number. Also provides methods for determining which locales have number formats, and what their names are.
NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points, thousands-separators, or even the particular decimal digits used, or whether the number format is even decimal.
To format a number for the current Locale, use one of the static factory methods:
.   double myNumber = 7.0;
.   UnicodeString myString;
.   UErrorCode success = U_ZERO_ERROR;
.   NumberFormat* nf = NumberFormat::createInstance(success)
.   nf->format(myNumber, myString);
.   cout << " Example 1: " << myString << endl;
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.
.    UnicodeString myString;
.    UErrorCode success = U_ZERO_ERROR;
.    nf = NumberFormat::createInstance( success );
.    int32_t a[] = { 123, 3333, -1234567 };
.    const int32_t a_len = sizeof(a) / sizeof(a[0]);
.    myString.remove();
.    for (int32_t i = 0; i < a_len; i++) {
.        nf->format(a[i], myString);
.        myString += " ; ";
.    }
.    cout << " Example 2: " << myString << endl;
To format a number for a different Locale, specify it in the call to createInstance().
.    nf = NumberFormat::createInstance( Locale::FRENCH, success );
You can use a NumberFormat to parse also.
.   UErrorCode success;
.   Formattable result(-999);  // initialized with error code
.   nf->parse(myString, result, success);
Use createInstance to get the normal number format for that country. There are other static factory methods available. Use getCurrency to get the currency number format for that country. Use getPercent to get a format for displaying percentages. With this format, a fraction from 0.53 is displayed as 53%.
You can also control the display of numbers with such methods as getMinimumFractionDigits. If you want even more control over the format or parsing, or want to give your users more control, you can try casting the NumberFormat you get from the factory methods to a DecimalNumberFormat. This will work for the vast majority of countries; just remember to put it in a try block in case you encounter an unusual one.
You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

(a) progressively parse through pieces of a string.
(b) align the decimal point and other areas.
For example, you can align numbers in two ways.
If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal, but possibly additional characters at the end, e.g. with parentheses in negative numbers: "(12)" for -12.

enum EAlignmentFields

Alignment Field constants used to construct a FieldPosition object. Signifies that the position of the integer part or fraction part of a formatted number should be returned.

See Also:: FieldPosition

INTEGER_FIELD: These constants are provided for backwards compatibility only, and are deprecated. Please use the C++ style constants defined above.

virtual bool_t operator==(const Format& other) const

Return true if the given Format objects are semantically equal. Objects of different subclasses are considered unequal.

virtual UnicodeString& format(const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const

Format an object to produce a string. This method handles Formattable objects with numeric types. If the Formattable object type is not a numeric type, then it returns a failing UErrorCode.

Returns:: The value passed in as toAppendTo (this allows chaining, as with UnicodeString::append())
Parameters:: obj - The object to format.
toAppendTo - Where the text is to be appended.
pos - On input: an alignment field, if desired. On output: the offsets of the alignment field.
status - Output param filled with success/failure status.

virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const

Parse a string to produce an object. This methods handles parsing of numeric strings into Formattable objects with numeric types.

Before calling, set parse_pos.index to the offset you want to start parsing at in the source. After calling, parse_pos.index is the end of the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with successful parse), while trailing whitespace is left as is.

See Format::parseObject() for more.

Returns:: A newly created Formattable* object, or NULL on failure. The caller owns this and should delete it when done.
Parameters:: source - The string to be parsed into an object.
result - Formattable to be set to the parse result. If parse fails, return contents are undefined.
parse_pos - The position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged.

UnicodeString& format( double number, UnicodeString& output) const

Format a double or long number. These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Returns:: A reference to 'output' param.
Parameters:: number - The value to be formatted.
output - Output param with the formatted string.

virtual UnicodeString& format(double number, UnicodeString& toAppendTo, FieldPosition& pos) const

Format a double or long number. Concrete subclasses must implement these pure virtual methods.

Returns:: A reference to 'toAppendTo'.
Parameters:: number - The value to be formatted.
toAppendTo - The string to append the formatted string to. This is an output parameter.
pos - On input: an alignment field, if desired. On output: the offsets of the alignment field.

UnicodeString& format(const Formattable& obj, UnicodeString& result, UErrorCode& status) const

Redeclared Format method

virtual void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const

Return a long if possible (e.g. within range LONG_MAX, LONG_MAX], and with no decimals), otherwise a double. If IntegerOnly is set, will stop at a decimal point (or equivalent; e.g. for rational numbers "1 2/3", will stop after the 1).

If no object can be parsed, index is unchanged, and NULL is returned.

This is a pure virtual which concrete subclasses must implement.

Returns:: A Formattable object of numeric type. The caller owns this an must delete it. NULL on failure.
Parameters:: text - The text to be parsed.
result - Formattable to be set to the parse result. If parse fails, return contents are undefined.
parsePosition - The position to start parsing at on input. On output, moved to after the last successfully parse character. On parse failure, does not change.

virtual void parse( const UnicodeString& text, Formattable& result, UErrorCode& status) const

Parse a string as a numeric value, and return a Formattable numeric object. This method parses integers only if IntegerOnly is set.

Returns:: A Formattable object of numeric type. The caller owns this an must delete it. NULL on failure.
Parameters:: text - The text to be parsed.
result - Formattable to be set to the parse result. If parse fails, return contents are undefined.
status - Success or failure output parameter.
See Also:: NumberFormat::isParseIntegerOnly

bool_t isParseIntegerOnly(void) const

Return true if this format will parse numbers as integers only. For example in the English locale, with ParseIntegerOnly true, the string "1234." would be parsed as the integer value 1234 and parsing would stop at the "." character. Of course, the exact format accepted by the parse operation is locale dependant and determined by sub-classes of NumberFormat.

virtual void setParseIntegerOnly(bool_t value)

Sets whether or not numbers should be parsed as integers only

See Also:: isParseIntegerOnly

static NumberFormat* createInstance(UErrorCode&)

Returns the default number format for the current default locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.

static NumberFormat* createInstance(const Locale& inLocale, UErrorCode&)

Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.

static NumberFormat* createCurrencyInstance(UErrorCode&)

Returns a currency format for the current default locale

static NumberFormat* createCurrencyInstance(const Locale& inLocale, UErrorCode&)

Returns a currency format for the specified locale

static NumberFormat* createPercentInstance(UErrorCode&)

Returns a percentage format for the current default locale

static NumberFormat* createPercentInstance(const Locale& inLocale, UErrorCode&)

Returns a percentage format for the specified locale

static NumberFormat* createScientificInstance(UErrorCode&)

Returns a scientific format for the current default locale

static NumberFormat* createScientificInstance(const Locale& inLocale, UErrorCode&)

Returns a scientific format for the specified locale

static const Locale* getAvailableLocales(int32_t& count)

Get the set of Locales for which NumberFormats are installed

bool_t isGroupingUsed(void) const

Returns true if grouping is used in this format. For example, in the English locale, with grouping on, the number 1234567 might be formatted as "1,234,567". The grouping separator as well as the size of each group is locale dependant and is determined by sub-classes of NumberFormat.

See Also:: setGroupingUsed

virtual void setGroupingUsed(bool_t newValue)

Set whether or not grouping will be used in this format

See Also:: getGroupingUsed

int32_t getMaximumIntegerDigits(void) const

Returns the maximum number of digits allowed in the integer portion of a number

See Also:: setMaximumIntegerDigits

virtual void setMaximumIntegerDigits(int32_t newValue)

Sets the maximum number of digits allowed in the integer portion of a number. maximumIntegerDigits must be >= minimumIntegerDigits. If the new value for maximumIntegerDigits is less than the current value of minimumIntegerDigits, then minimumIntegerDigits will also be set to the new value.

See Also:: getMaximumIntegerDigits

int32_t getMinimumIntegerDigits(void) const

Returns the minimum number of digits allowed in the integer portion of a number

See Also:: setMinimumIntegerDigits

virtual void setMinimumIntegerDigits(int32_t newValue)

Sets the minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits exceeds the current value of maximumIntegerDigits, then maximumIntegerDigits will also be set to the new value.

See Also:: getMinimumIntegerDigits

int32_t getMaximumFractionDigits(void) const

Returns the maximum number of digits allowed in the fraction portion of a number

See Also:: setMaximumFractionDigits

virtual void setMaximumFractionDigits(int32_t newValue)

Sets the maximum number of digits allowed in the fraction portion of a number. maximumFractionDigits must be >= minimumFractionDigits. If the new value for maximumFractionDigits is less than the current value of minimumFractionDigits, then minimumFractionDigits will also be set to the new value.

See Also:: getMaximumFractionDigits

int32_t getMinimumFractionDigits(void) const

Returns the minimum number of digits allowed in the fraction portion of a number

See Also:: setMinimumFractionDigits

virtual void setMinimumFractionDigits(int32_t newValue)

Sets the minimum number of digits allowed in the fraction portion of a number. minimumFractionDigits must be <= maximumFractionDigits. If the new value for minimumFractionDigits exceeds the current value of maximumFractionDigits, then maximumIntegerDigits will also be set to the new value

See Also:: getMinimumFractionDigits

static UClassID getStaticClassID(void)

Return the class ID for this class. This is useful only for comparing to a return value from getDynamicClassID(). For example:

.   Base* polymorphic_pointer = createPolymorphicObject();
.   if (polymorphic_pointer->getDynamicClassID() ==
.       Derived::getStaticClassID()) ...

Returns:: The class ID for all objects of this class.

virtual UClassID getDynamicClassID(void) const

Override Calendar Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.